Introduction

يوضّح هذا المستند أوجه التشابه والاختلاف في الطرق التي تتيح بها واجهة برمجة التطبيقات YouTube Analytics API وYouTube Reporting API الوصول إلى بيانات "إحصاءات YouTube". والغرض من المستند هو مساعدتك على اختيار واجهة برمجة التطبيقات المناسبة لتطبيقك.

وتمكّن كلٌّ من واجهتَي برمجة التطبيقات من استرداد بيانات "إحصاءات YouTube". بالإضافة إلى ذلك، تدعم كلتا الواجهتين مالكي قنوات YouTube ومالكي المحتوى على YouTube، الذين يمكن لكل منهم الوصول إلى مجموعة محددة من التقارير:

  • تحتوي تقارير القنوات على مقاييس نشاط المستخدم لقناة محدّدة.

  • تقارير مالك المحتوى تتضمن مقاييس مجمَّعة لكل القنوات المرتبطة بمالك محتوى محدّد على YouTube. على سبيل المثال، يمكن لشركة إنتاج استرداد تقرير يحتوي على إحصاءات مجمّعة لقنوات YouTube التي تضم كل فنّاني شركة الإنتاج الموسيقي. تحتوي بعض تقارير مالكي المحتوى على مقاييس نشاط المستخدم، بينما يحتوي البعض الآخر على مقاييس متعلقة بالأرباح وأداء الإعلانات.

تتيح Reporting API أيضًا لبعض مالكي المحتوى الوصول إلى تقارير أرباح الإعلانات التي يديرها النظام. لا يمكن استرداد البيانات في التقارير التي يديرها النظام إلا باستخدام Reporting API.

يجب أن يوافق مالك القناة أو المحتوى الذي يملك البيانات المطلوبة على كلّ طلبات "إحصاءات YouTube" وواجهة برمجة التطبيقات لإعداد التقارير في YouTube.

محتوى التقرير

تحتوي التقارير التي تستردها واجهات برمجة التطبيقات على نوعين من البيانات:

  • السمات هي معايير شائعة تُستخدَم لتجميع البيانات، مثل تاريخ حدوث نشاط المستخدِم أو البلد الذي كان يوجد فيه المستخدمون.

    في أيّ تقرير، يحتوي كلّ صف من البيانات على مجموعة فريدة من قيم السمات. وعلى هذا النحو، تعمل مجموعة قيم الأبعاد في كل صف كمفتاح أساسي لذلك الصف.

  • المقاييس هي مقاييس فردية لنشاط المستخدم أو أداء الإعلانات أو الأرباح المقدّرة. وتشمل مقاييس نشاط المستخدم عناصر مثل عدد مشاهدات الفيديو والتقييمات (الإعجابات وغير المعجبين).

اختيار واجهة برمجة التطبيقات المناسبة لتطبيقك

YouTube Analytics API
تتيح YouTube Analytics API طلبات البحث المستهدفة في الوقت الفعلي لإنشاء تقارير مخصّصة في "إحصاءات YouTube". توفر واجهة برمجة التطبيقات معلمات التصفية والترتيب، بحيث لا يحتاج تطبيق الاتصال إلى دعم هذه الدوال بشكل أصلي.

يحدّد كل طلب من طلبات البيانات من واجهة برمجة التطبيقات النطاق الزمني الذي سيتم عرض البيانات فيه. تتيح لك واجهة برمجة التطبيقات أيضًا استرداد مجموعات البيانات الأسبوعية والشهرية. وبناءً على ذلك، لا يحتاج تطبيق الاتصال إلى تخزين مجموعات البيانات التي تم استردادها أو تجميع الإحصاءات عبر النطاقات الزمنية.
واجهة برمجة التطبيقات لإعداد التقارير في YouTube
تسترد YouTube Reporting API التقارير المجمّعة التي تتضمّن بيانات "إحصاءات YouTube" لقناة أو مالك محتوى. وهي مصممة للتطبيقات التي يمكنها استيراد مجموعات بيانات كبيرة وتوفر أدوات لتصفية تلك البيانات وفرزها والتنقيب عنها.

يحتوي كل تقرير على مجموعة محدّدة مسبقًا من الحقول. يستخدم المطوّرون واجهة برمجة التطبيقات لجدولة مهام إعداد التقارير، وتحدّد كل منها تقريرًا يجب أن تنشئه منصة YouTube. بعد ذلك، ينشئ YouTube تقريرًا يوميًا يمكن تنزيله بشكل غير متزامن. يحتوي كل تقرير على بيانات فريدة لمدة 24 ساعة.

بالإضافة إلى ذلك، تنشئ منصة YouTube تلقائيًا مجموعة من التقارير التي يديرها النظام لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير المناسبة في استوديو YouTube لصنّاع المحتوى. تتيح هذه التقارير إمكانية الوصول الآلي إلى بيانات أرباح الإعلانات.

التقارير المتاحة

يحدّد الجدول التالي الأنواع المختلفة من التقارير التي يمكنك استردادها باستخدام واجهات برمجة التطبيقات. وتتوفر طلبات البحث المستهدفة عبر YouTube Analytics API، وتتوفر التقارير المجمّعة عبر YouTube Reporting API.

فالبيانات المتوفرة في إحدى واجهات برمجة التطبيقات قد لا تكون متوفرة في الأخرى. على سبيل المثال، تتيح لك واجهة برمجة تطبيقات YouTube Analytics استرداد مقاييس نشاط المستخدم على أساس أسبوعي أو شهري، ولكن تتطلب منك واجهة برمجة التطبيقات لإعداد التقارير في YouTube تجميع تلك البيانات بنفسك. من ناحية أخرى، تتيح واجهة برمجة التطبيقات لإعداد التقارير في YouTube إمكانية إعداد تقارير مواد العرض لمالكي المحتوى، ولكن لا تتوفر هذه البيانات من واجهة برمجة تطبيقات YouTube Analytics.

أنواع التقارير
تقارير الفيديوهات هذا الخيار متاح للقنوات (طلب بحث أو مجمّع) ومالكي المحتوى (طلب أو مجمّع).

تقدّم تقارير الفيديو إحصاءات حول جميع أنشطة المستخدمين المرتبطة بالفيديوهات المنشورة على القناة أو بفيديوهات مالك المحتوى. على سبيل المثال، تتضمّن هذه التقارير عدد المشاهدات التي حصدتها فيديوهاتك. في YouTube Analytics API، تتضمّن بعض تقارير فيديوهات مالك المحتوى أيضًا مقاييس الأرباح وأداء الإعلانات المقدّرة.
تقارير قوائم التشغيل هذا الخيار متاح للقنوات (طلب بحث أو مجمّع) ومالكي المحتوى (طلب أو مجمّع).

تقدّم تقارير قوائم التشغيل إحصاءات مرتبطة تحديدًا بمشاهدات الفيديو التي تتم في سياق قائمة تشغيل. تتيح YouTube Reporting API إعداد تقارير حول الاحتفاظ بالجمهور لقوائم التشغيل، ولكن لا يمكن استخدام تقرير مماثل في YouTube Analytics API.
تقارير أداء الإعلان يتوفر هذا الخيار لمالكي المحتوى (طلب بحث أو مجمّع).

توفّر تقارير أداء الإعلانات مقاييس مستندة إلى مرّات الظهور للإعلانات التي تمّ عرضها خلال عمليات تشغيل الفيديوهات. تأخذ هذه المقاييس في الحسبان كل مرة ظهور للإعلان، ويمكن أن تؤدي كل عملية تشغيل للفيديو إلى مرات ظهور متعددة.
تقارير الأرباح المقدَّرة هذا الخيار متاح لمالكي المحتوى (بشكل مجمّع).

تقدّم تقارير الأرباح المقدّرة إجمالي الأرباح المقدّرة للفيديوهات الواردة من مصادر الإعلانات التي تبيعها Google والمصادر غير الإعلانية. تحتوي هذه التقارير أيضًا على بعض مقاييس أداء الإعلانات. تجدر الإشارة إلى أنّ التقارير التي يديرها النظام تتضمّن الأرباح الفعلية.
تقارير مواد العرض هذا الخيار متاح لمالكي المحتوى (بشكل مجمّع).

تقدّم تقارير مواد العرض مقاييس نشاط المستخدم المتعلّقة بالفيديوهات المرتبطة بمواد عرض مالك المحتوى. يتم تضمين فيديو في تقرير مالك المحتوى إذا كان مالك المحتوى قد طالب بملكية هذا الفيديو على أنّه محتوى مطابق لإحدى مواد العرض الخاصة به. من الممكن أن يكون قد حمّل الفيديو مالك المحتوى أو مستخدم آخر على YouTube.
التقارير التي يديرها النظام تتوفر هذه الميزة لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير المناسبة في قائمة "التقارير" في "استوديو صنّاع المحتوى على YouTube".

تقدّم التقارير التي يديرها النظام بيانات الأرباح الفعلية التي حقّقتها مواد العرض والفيديوهات. يتضمّن التقرير الإضافي قائمة بالفيديوهات التي تمّت المطالبة بملكيتها ومواد العرض التي تتطابق مع هذه الفيديوهات. تجدر الإشارة إلى أنّ واجهة برمجة التطبيقات لا تتوفّر حاليًا بعض تقارير "استوديو صنّاع المحتوى".

ملاحظة: تنشئ منصة YouTube تلقائيًا تقارير يديرها النظام لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير المقابلة في "استوديو صنّاع المحتوى". ونتيجةً لذلك، تختلف عملية استرداد هذه التقارير عن الأنواع الأخرى من التقارير في هذه القائمة. راجع وثائق التقارير التي يديرها النظام للحصول على مزيد من المعلومات.

الاختلافات الرئيسية

يسلّط الجدول التالي الضوء على الاختلافات المهمة بين "إحصاءات YouTube" وواجهات برمجة التطبيقات لإعداد التقارير.

إبراز YouTube Analytics API واجهة برمجة التطبيقات لإعداد التقارير في YouTube
عملية استرداد البيانات يحدّد كل طلب من واجهة برمجة التطبيقات السمات والمقاييس التي سيتم عرضها، بالإضافة إلى الفترة الزمنية التي سيتم عرض البيانات خلالها. وظائف إعداد تقارير بشأن جداول التطبيقات ينشئ YouTube تقارير يومية يمكن تنزيلها بشكل غير متزامن لكل مهمة.
النطاقات الزمنية تحدّد بعض تقارير واجهة برمجة التطبيقات تاريخ حدوث نشاط المستخدم. وتتيح بعض هذه التقارير سمات لتجميع مقاييس نشاط المستخدم حسب الشهر. تحدد جميع تقارير واجهة برمجة التطبيقات يوم حدوث نشاط المستخدم. يمكن للتطبيقات التي تستخدم واجهة برمجة التطبيقات تنفيذ ميزات لتجميع البيانات على فترات دورية.
فلترة البيانات يمكنك فلترة التقارير لتضمين الصفوف التي يكون للسمة فيها قيمة معيّنة فقط. وتدعم واجهة برمجة التطبيقات أيضًا بعض الأبعاد، مثل القارة وsubContinent، التي تُستخدم كفلاتر فقط. تتيح واجهة برمجة التطبيقات إجراء عمليات تنزيل مجمّعة لمجموعات البيانات الكاملة. ولا تتيح هذه الميزة فلترة البيانات أو عرضها للسمات المخصّصة للفلتر فقط. يخزن تطبيق العميل البيانات التي يتم تنزيلها وينفذ ميزاته الخاصة لتصفية البيانات.
التصنيف يمكن ترتيب التقارير استنادًا إلى قيم المقاييس المعروضة. تحتوي بعض التقارير على عدد محدود فقط من النتائج. على سبيل المثال، يعرض التقرير الذي يعرض أكثر الفيديوهات مشاهدةً على القناة 200 صف كحدٍّ أقصى. تتيح واجهة برمجة التطبيقات هذه إجراء عمليات تنزيل مجمّعة لمجموعات البيانات الكاملة. يمكن لتطبيقات العميل تنفيذ ميزاتها الخاصة لفرز البيانات التي يتم تنزيلها.
عمليات التعداد تحتوي تقارير واجهة برمجة التطبيقات على قيم نصية، مثل "ANDROID" أو "CHANNEL"، لتحديد قيم السمات العددية. تحتوي تقارير واجهة برمجة التطبيقات على أعداد صحيحة يمكن ربطها بقيم نصية.
الحصة يقيّم خادم واجهة برمجة التطبيقات كل طلب بحث لتحديد تكلفة الحصة. يشرح قسم استخدام الحصة المنهجية بمزيد من التفصيل. لا يمثل استخدام الحصة مشكلة لأنه يتم استرداد البيانات مرة واحدة ثم تصفيتها وفرزها والاستعلام عنها داخل التطبيق.
التقارير الفريدة
  • نشاط المستخدم المتعلّق بالترجمة
  • بيانات الاحتفاظ بالجمهور لقوائم التشغيل
  • تقارير الأرباح المقدَّرة لمالكي المحتوى (يتوفّر تقريران مختلفان)
  • تقارير مواد العرض لمالكي المحتوى (يتوفّر 11 تقريرًا مختلفًا)
السمات الفريدة group (سمة للفلتر فقط)
continent (سمة الفلتر فقط)
subContinent (سمة متعلقة بالفلتر فقط)
الشهر
isCurated==1 (مكوّن للفلتر فقط)
viewsPerPlaylistStart
averageTimeInPlaylist
annotation_id
annotation_type
asset_id
card_id
card_type
live_or_on_demand
subscribed_status
subtitle_language
المقاييس الفريدة الفريدات
relativeRetentionPerformance
viewsPerPlaylistStart
averageTimeInPlaylist
card_click_rate
card_clicks
card_impressions<br class="ph-1-6"
card_clicks<br class="ph-impression_rate<br class="br class="ph-1-1">
.




card_teaser_click_ratecard_teaser_clickscard_teaser_impressionsestimated_partner_adsense_revenueestimated_partner_doubleclick_revenueplaylist_saves_addedplaylist_saves_removed

الاختلافات في التسمية بين واجهات برمجة التطبيقات

تستخدِم واجهتا برمجة التطبيقات حاليًا اصطلاحات تسمية مختلفة لتحديد السمات والمقاييس. في الوقت الحالي، تستخدم أسماء YouTube Analytics API CamlCase، بينما تستخدم أسماء واجهة برمجة التطبيقات لإعداد التقارير في YouTube أسماءً يتم الفصل بينها باستخدام الشرطة السفلية.

تحدد الجداول التالية الأسماء المختلفة التي تستخدمها واجهتا برمجة التطبيقات لتحديد المقاييس والأبعاد نفسها. في بعض الحالات، يكون الفرق بين الاسمين أكبر مما ستحصل عليه بعد تحويل الاسم من CamlCase إلى شرطات سفلية. على سبيل المثال، تتم تسمية السمة video في واجهة برمجة تطبيقات YouTube Analytics باسم video_id في YouTube Reporting API.

الأبعاد

اسم واجهة برمجة تطبيقات YouTube Analytics اسم YouTube Reporting API
adType ad_type
ageGroup age_group
مادة عرض asset_id
audienceType audience_retention_type
قناة channel_id
claimedStatus claimed_status
contentOwner content_owner_id
country country_code
يوم التاريخ
deviceType device_type
elapsedVideoTimeRatio elapsed_video_time_percentage
gender (الجنس) gender (الجنس)
insightPlaybackLocationDetail playback_location_detail
insightPlaybackLocationType playback_location_type
insightTrafficSourceDetail traffic_source_detail
insightTrafficSourceType traffic_source_type
liveOrOnDemand live_or_on_demand
operatingSystem operating_system
قائمة تشغيل playlist_id
province province_code
sharingService sharing_service
subscribedStatus subscribed_status
subtitleLanguage subtitle_language
uploaderType uploader_type
فيديو video_id

المقاييس

اسم واجهة برمجة تطبيقات YouTube Analytics اسم YouTube Reporting API
adEarnings estimated_partner_ad_revenue
annotationImpressions annotation_impressions
annotationClickableImpressions annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpressions annotation_closable_impressions
annotationCloses annotation_closes
annotationCloseRate annotation_close_rate
audienceWatchRatio audience_retention_percentage
averageViewDuration average_view_duration_seconds
averageViewPercentage average_view_duration_percentage
cardClickRate card_click_rate
cardClicks card_clicks
cardImpressions card_impressions
cardTeaserClickRate card_teaser_click_rate
cardTeaserClicks card_teaser_clicks
cardTeaserImpressions card_teaser_impressions
التعليقات التعليقات
من غير المعجبين من غير المعجبين
الأرباح estimated_partner_revenue
estimatedMinutesWatched watch_time_minutes
estimatedPartnerAdSenseRevenue estimated_partner_adsense_revenue
estimatedPartnerDoubleClickRevenue estimated_partner_doubleclick_revenue
grossRevenue estimated_youtube_ad_revenue
impressionBasedCpm estimated_cpm
مرّة ظهور ad_impressions
عدد المعجبين عدد المعجبين
monetizedPlaybacks estimated_monetized_playbacks
playbackBasedCpm estimated_playback_based_cpm
playlistStarts playlist_starts
savesAdded playlist_saves_added
savesRemoved playlist_saves_removed
مشاركة مشاركة
subscribersGained subscribers_gained
subscribersLost subscribers_lost
videosAddedToPlaylists videos_added_to_playlists
videosRemovedFromPlaylists videos_removed_from_playlist
viewerPercentage views_percentage
مشاهدة مشاهدة